home *** CD-ROM | disk | FTP | other *** search
/ Visual Cafe 3 / Visual Cafe 3.ISO / Vcafe / Main.bin / InputStream.java < prev    next >
Text File  |  1998-09-22  |  9KB  |  234 lines
  1. /*
  2.  * @(#)InputStream.java    1.22 98/07/01
  3.  *
  4.  * Copyright 1995-1998 by Sun Microsystems, Inc.,
  5.  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
  6.  * All rights reserved.
  7.  * 
  8.  * This software is the confidential and proprietary information
  9.  * of Sun Microsystems, Inc. ("Confidential Information").  You
  10.  * shall not disclose such Confidential Information and shall use
  11.  * it only in accordance with the terms of the license agreement
  12.  * you entered into with Sun.
  13.  */
  14.  
  15. package java.io;
  16.  
  17. /**
  18.  * This abstract class is the superclass of all classes representing 
  19.  * an input stream of bytes. 
  20.  * <p>
  21.  * Applications that need to define a subclass of 
  22.  * <code>InputStream</code> must always provide a method that returns 
  23.  * the next byte of input.
  24.  * 
  25.  * @author  Arthur van Hoff
  26.  * @version 1.22, 07/01/98
  27.  * @see     java.io.BufferedInputStream
  28.  * @see     java.io.ByteArrayInputStream
  29.  * @see     java.io.DataInputStream
  30.  * @see     java.io.FilterInputStream
  31.  * @see     java.io.InputStream#read()
  32.  * @see     java.io.OutputStream
  33.  * @see     java.io.PushbackInputStream
  34.  * @since   JDK1.0
  35.  */
  36. public abstract class InputStream {
  37.     /**
  38.      * Reads the next byte of data from this input stream. The value 
  39.      * byte is returned as an <code>int</code> in the range 
  40.      * <code>0</code> to <code>255</code>. If no byte is available 
  41.      * because the end of the stream has been reached, the value 
  42.      * <code>-1</code> is returned. This method blocks until input data 
  43.      * is available, the end of the stream is detected, or an exception 
  44.      * is thrown. 
  45.      * <p>
  46.      * A subclass must provide an implementation of this method. 
  47.      *
  48.      * @return     the next byte of data, or <code>-1</code> if the end of the
  49.      *             stream is reached.
  50.      * @exception  IOException  if an I/O error occurs.
  51.      * @since      JDK1.0
  52.      */
  53.     public abstract int read() throws IOException;
  54.  
  55.     /**
  56.      * Reads up to <code>b.length</code> bytes of data from this input 
  57.      * stream into an array of bytes. 
  58.      * <p>
  59.      * The <code>read</code> method of <code>InputStream</code> calls 
  60.      * the <code>read</code> method of three arguments with the arguments 
  61.      * <code>b</code>, <code>0</code>, and <code>b.length</code>. 
  62.      *
  63.      * @param      b   the buffer into which the data is read.
  64.      * @return     the total number of bytes read into the buffer, or
  65.      *             <code>-1</code> is there is no more data because the end of
  66.      *             the stream has been reached.
  67.      * @exception  IOException  if an I/O error occurs.
  68.      * @see        java.io.InputStream#read(byte[], int, int)
  69.      * @since      JDK1.0
  70.      */
  71.     public int read(byte b[]) throws IOException {
  72.     return read(b, 0, b.length);
  73.     }
  74.  
  75.     /**
  76.      * Reads up to <code>len</code> bytes of data from this input stream 
  77.      * into an array of bytes. This method blocks until some input is 
  78.      * available. If the argument <code>b</code> is <code>null</code>, a  
  79.      * <code>NullPointerException</code> is thrown.
  80.      * <p>
  81.      * The <code>read</code> method of <code>InputStream</code> reads a 
  82.      * single byte at a time using the read method of zero arguments to 
  83.      * fill in the array. Subclasses are encouraged to provide a more 
  84.      * efficient implementation of this method. 
  85.      *
  86.      * @param      b     the buffer into which the data is read.
  87.      * @param      off   the start offset of the data.
  88.      * @param      len   the maximum number of bytes read.
  89.      * @return     the total number of bytes read into the buffer, or
  90.      *             <code>-1</code> if there is no more data because the end of
  91.      *             the stream has been reached.
  92.      * @exception  IOException  if an I/O error occurs.
  93.      * @see        java.io.InputStream#read()
  94.      * @since      JDK1.0
  95.      */
  96.     public int read(byte b[], int off, int len) throws IOException {
  97.     if (len <= 0) {
  98.         return 0;
  99.     }
  100.  
  101.     int c = read();
  102.     if (c == -1) {
  103.         return -1;
  104.     }
  105.     b[off] = (byte)c;
  106.  
  107.     int i = 1;
  108.     try {
  109.         for (; i < len ; i++) {
  110.         c = read();
  111.         if (c == -1) {
  112.             break;
  113.         }
  114.         if (b != null) {
  115.             b[off + i] = (byte)c;
  116.         }
  117.         }
  118.     } catch (IOException ee) {
  119.     }
  120.     return i;
  121.     }
  122.  
  123.     /**
  124.      * Skips over and discards <code>n</code> bytes of data from this 
  125.      * input stream. The <code>skip</code> method may, for a variety of 
  126.      * reasons, end up skipping over some smaller number of bytes, 
  127.      * possibly <code>0</code>. The actual number of bytes skipped is 
  128.      * returned. 
  129.      * <p>
  130.      * The <code>skip</code> method of <code>InputStream</code> creates 
  131.      * a byte array of length <code>n</code> and then reads into it until 
  132.      * <code>n</code> bytes have been read or the end of the stream has 
  133.      * been reached. Subclasses are encouraged to provide a more 
  134.      * efficient implementation of this method. 
  135.      *
  136.      * @param      n   the number of bytes to be skipped.
  137.      * @return     the actual number of bytes skipped.
  138.      * @exception  IOException  if an I/O error occurs.
  139.      * @since      JDK1.0
  140.      */
  141.     public long skip(long n) throws IOException {
  142.     /* ensure that the number is a positive int */
  143.     byte data[] = new byte[(int) (n & 0xEFFFFFFF)];
  144.     return read(data);
  145.     }
  146.  
  147.     /**
  148.      * Returns the number of bytes that can be read from this input 
  149.      * stream without blocking. The available method of 
  150.      * <code>InputStream</code> returns <code>0</code>. This method 
  151.      * <B>should</B> be overridden by subclasses. 
  152.      *
  153.      * @return     the number of bytes that can be read from this input stream
  154.      *             without blocking.
  155.      * @exception  IOException  if an I/O error occurs.
  156.      * @since       JDK1.0
  157.      */
  158.     public int available() throws IOException {
  159.     return 0;
  160.     }
  161.  
  162.     /**
  163.      * Closes this input stream and releases any system resources 
  164.      * associated with the stream. 
  165.      * <p>
  166.      * The <code>close</code> method of <code>InputStream</code> does nothing.
  167.      *
  168.      * @exception  IOException  if an I/O error occurs.
  169.      * @since      JDK1.0
  170.      */
  171.     public void close() throws IOException {}
  172.  
  173.     /**
  174.      * Marks the current position in this input stream. A subsequent 
  175.      * call to the <code>reset</code> method repositions this stream at 
  176.      * the last marked position so that subsequent reads re-read the same 
  177.      * bytes. 
  178.      * <p>
  179.      * The <code>readlimit</code> arguments tells this input stream to 
  180.      * allow that many bytes to be read before the mark position gets 
  181.      * invalidated. 
  182.      * <p>
  183.      * The <code>mark</code> method of <code>InputStream</code> does nothing.
  184.      *
  185.      * @param   readlimit   the maximum limit of bytes that can be read before
  186.      *                      the mark position becomes invalid.
  187.      * @see     java.io.InputStream#reset()
  188.      * @since   JDK1.0
  189.      */
  190.     public synchronized void mark(int readlimit) {}
  191.  
  192.     /**
  193.      * Repositions this stream to the position at the time the 
  194.      * <code>mark</code> method was last called on this input stream. 
  195.      * <p>
  196.      * The <code>reset</code> method of <code>InputStream</code> throws 
  197.      * an <code>IOException</code>, because input streams, by default, do 
  198.      * not support <code>mark</code> and <code>reset</code>.
  199.      * <p>
  200.      * Stream marks are intended to be used in
  201.      * situations where you need to read ahead a little to see what's in
  202.      * the stream. Often this is most easily done by invoking some
  203.      * general parser. If the stream is of the type handled by the
  204.      * parser, it just chugs along happily. If the stream is not of
  205.      * that type, the parser should toss an exception when it fails,
  206.      * which, if it happens within readlimit bytes, allows the outer
  207.      * code to reset the stream and try another parser.
  208.      *
  209.      * @exception  IOException  if this stream has not been marked or if the
  210.      *               mark has been invalidated.
  211.      * @see     java.io.InputStream#mark(int)
  212.      * @see     java.io.IOException
  213.      * @since   JDK1.0
  214.      */
  215.     public synchronized void reset() throws IOException {
  216.     throw new IOException("mark/reset not supported");
  217.     }
  218.  
  219.     /**
  220.      * Tests if this input stream supports the <code>mark</code> 
  221.      * and <code>reset</code> methods. The <code>markSupported</code> 
  222.      * method of <code>InputStream</code> returns <code>false</code>. 
  223.      *
  224.      * @return  <code>true</code> if this true type supports the mark and reset
  225.      *          method; <code>false</code> otherwise.
  226.      * @see     java.io.InputStream#mark(int)
  227.      * @see     java.io.InputStream#reset()
  228.      * @since   JDK1.0
  229.      */
  230.     public boolean markSupported() {
  231.     return false;
  232.     }
  233. }
  234.